Frontend WebHID-enhetsfilter: En förklaring av val av mänskliga gränssnittsenheter

WebHID API:et öppnar upp en värld av möjligheter för webbapplikationer, vilket gör att de kan interagera direkt med mänskliga gränssnittsenheter (HID) som spelkontroller, specialiserade inmatningsenheter och mer. En kritisk del av att använda WebHID effektivt är att förstå enhetsfilter. Denna omfattande guide kommer att gå igenom allt du behöver veta om WebHID-enhetsfilter, vilket ger dig möjlighet att skapa kraftfulla och engagerande webbupplevelser.

Vad är WebHID?

WebHID är ett webb-API som gör det möjligt för webbapplikationer att kommunicera med HID-enheter anslutna till en användares dator eller mobila enhet. Till skillnad från traditionella webb-API:er som förlitar sig på specifika drivrutiner, tillhandahåller WebHID ett generiskt gränssnitt för att interagera med ett brett utbud av enheter, så länge användaren ger sitt tillstånd. Detta gör det idealiskt för enheter som inte har inbyggt webbläsarstöd eller kräver anpassad inmatningshantering.

Varför använda WebHID?

• Direkt enhetsåtkomst: Kommunicera direkt med HID-enheter utan att vara beroende av webbläsarspecifika drivrutiner.
• Anpassad inmatningshantering: Implementera anpassad inmatningsmappning och bearbetning för specialiserade enheter.
• Brett enhetsstöd: Stöd för ett bredare utbud av enheter, inklusive spelkontroller, vetenskapliga instrument och industriella styrenheter.
• Förbättrad användarupplevelse: Skapa mer uppslukande och interaktiva webbupplevelser.

Förstå WebHID-enhetsfilter

Enhetsfilter är avgörande för att begära åtkomst till specifika HID-enheter. När din webbapplikation anropar navigator.hid.requestDevice(), visar webbläsaren en enhetsväljare som låter användaren välja en enhet. Enhetsfilter låter dig begränsa listan över enheter som presenteras för användaren, vilket gör det lättare för dem att hitta den rätta.

Ett enhetsfilter är ett JavaScript-objekt som specificerar kriterier för att matcha HID-enheter. Du kan specificera flera filter i anropet till requestDevice(), och webbläsaren kommer endast att visa enheter som matchar minst ett av filtren.

Egenskaper för enhetsfilter

• vendorId (valfri): Enhetens USB Vendor ID. Detta är ett 16-bitars tal som identifierar tillverkaren av enheten.
• productId (valfri): Enhetens USB Product ID. Detta är ett 16-bitars tal som identifierar den specifika modellen av enheten.
• usagePage (valfri): Enhetens HID Usage Page. Detta identifierar enhetens kategori (t.ex. Generic Desktop Controls, Game Controls).
• usage (valfri): Enhetens HID Usage. Detta identifierar enhetens specifika funktion inom dess usage page (t.ex. Joystick, Gamepad).

Du kan använda en kombination av dessa egenskaper för att skapa mycket specifika filter. Till exempel kan du filtrera efter enheter med ett specifikt vendorId och productId för att rikta in dig på en viss modell av spelkontroll.

Praktiska exempel på enhetsfilter

Låt oss titta på några praktiska exempel på hur man använder enhetsfilter i dina webbapplikationer.

Exempel 1: Filtrering för en specifik spelkontroll

Anta att du vill rikta in dig på en specifik spelkontroll med ett känt vendorId och productId. Du kan använda följande filter:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360-kontroll
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Hantera den/de valda enheten/enheterna
  })
  .catch((error) => {
    // Hantera fel
  });

            

              
                Copy
              
            
          

I det här exemplet kommer filtret endast att matcha enheter med ett vendorId på 0x045e (Microsoft) och ett productId på 0x028e (Xbox 360 Controller). Ersätt dessa med lämpligt Vendor ID och Product ID för den enhet du riktar in dig på.

Exempel 2: Filtrering för valfri spelkontroll

Om du vill tillåta användaren att välja vilken spelkontroll som helst kan du använda ett filter som specificerar usagePage och usage för spelkontroller:

            const filters = [
  {
    usagePage: 0x01, // Generic Desktop Controls
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Hantera den/de valda enheten/enheterna
  })
  .catch((error) => {
    // Hantera fel
  });

            

              
                Copy
              
            
          

Detta filter kommer att matcha alla HID-enheter som identifierar sig som en spelkontroll med hjälp av standardiserade HID-användningskoder.

Exempel 3: Kombinera filter

Du kan kombinera flera filter för att ge mer flexibilitet. Till exempel kanske du vill tillåta användaren att välja antingen en specifik spelkontrollmodell eller vilken spelkontroll som helst:

            const filters = [
  {
    vendorId: 0x045e, // Microsoft
    productId: 0x028e, // Xbox 360-kontroll
  },
  {
    usagePage: 0x01, // Generic Desktop Controls
    usage: 0x05, // Gamepad
  },
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Hantera den/de valda enheten/enheterna
  })
  .catch((error) => {
    // Hantera fel
  });

            

              
                Copy
              
            
          

I det här fallet kommer enhetsväljaren att visa både den specifika Xbox 360-kontrollen (om ansluten) och alla andra enheter som identifierar sig som en spelkontroll.

Exempel 4: Filtrering för en specifik tangentbordstyp på ett system

Vissa nischtangentbord kräver specifika HID-koder för att initieras korrekt. Följande exempel förutsätter att du känner till leverantörs-ID, produkt-ID, användningssida och användning för tangentbordet. Du kan vanligtvis hitta denna information i tillverkarens dokumentation eller med hjälp av enhetslistningsverktyg som finns tillgängliga på de flesta operativsystem.

            const filters = [
    {
        vendorId: 0x1234,  // Ersätt med ditt leverantörs-ID
        productId: 0x5678, // Ersätt med ditt produkt-ID
        usagePage: 0x07,   // Ersätt med din användningssida (t.ex. Keyboard/Keypad)
        usage: 0x01      // Ersätt med din användning (t.ex. Keyboard)
    }
];

navigator.hid.requestDevice({ filters })
  .then((devices) => {
    // Hantera den/de valda enheten/enheterna
  })
  .catch((error) => {
    // Hantera fel
  });

            

              
                Copy
              
            
          

Hämta enhetsinformation

När användaren har valt en enhet kan du komma åt dess information med hjälp av HIDDevice-objektet.

Egenskaper för HIDDevice

• vendorId: Enhetens USB Vendor ID.
• productId: Enhetens USB Product ID.
• productName: Enhetens namn.
• collections: En array av HIDCollection-objekt som representerar enhetens HID-rapportbeskrivningar.

Du kan använda denna information för att identifiera enheten och konfigurera din applikation därefter.

Hantera HID-rapporter

När du har fått ett HIDDevice-objekt måste du öppna det och börja lyssna efter HID-rapporter. HID-rapporter är rådata som skickas av enheten till din applikation.

Öppna enheten

            device.open()
  .then(() => {
    console.log('Enheten öppnad');

    // Börja lyssna efter inmatningsrapporter
    device.addEventListener('inputreport', (event) => {
      const { data, reportId } = event;
      // Bearbeta inmatningsrapporten
      console.log(`Mottog inmatningsrapport med ID ${reportId}:`, data);
    });
  })
  .catch((error) => {
    console.error('Misslyckades med att öppna enheten:', error);
  });

            

              
                Copy
              
            
          

Bearbeta inmatningsrapporter

Inmatningsrapporter tas emot som DataView-objekt. Datastrukturen beror på enhetens HID-rapportbeskrivning. Du måste konsultera enhetens dokumentation för att förstå hur datan ska tolkas.

Här är ett förenklat exempel på hur man bearbetar en inmatningsrapport:

            device.addEventListener('inputreport', (event) => {
  const { data, reportId } = event;

  // Antar att den första byten i rapporten representerar knappstatus
  const buttonState = data.getUint8(0);

  // Bearbeta knappstatus
  if (buttonState & 0x01) {
    console.log('Knapp 1 nedtryckt');
  }
  if (buttonState & 0x02) {
    console.log('Knapp 2 nedtryckt');
  }
});

            

              
                Copy
              
            
          

Detta är ett mycket grundläggande exempel. Verkliga HID-enheter har ofta mer komplexa rapportstrukturer. Att baklängeskonstruera (reverse engineering) HID-rapporten kan vara en komplex process; det finns dock verktyg som hjälper till med tolkningsprocessen.

Felhantering

Det är viktigt att hantera fel elegant när man arbetar med WebHID. Här är några vanliga fel du kan stöta på:

• SecurityError: Användaren har nekat åtkomst till HID-enheter.
• NotFoundError: Inga matchande enheter hittades.
• InvalidStateError: Enheten är redan öppen.
• Andra fel: USB-fel, oväntade frånkopplingar av enheter.

Omslut alltid din WebHID-kod i try...catch-block och ge informativa felmeddelanden till användaren.

Bästa praxis för WebHID-utveckling

• Använd enhetsfilter: Använd alltid enhetsfilter för att begränsa listan över enheter som presenteras för användaren.
• Ge tydliga instruktioner: Vägled användare om hur de ansluter och godkänner enheten. Om enheten inte dyker upp, förklara för användaren var man hittar Vendor ID och Product ID för vanliga enheter.
• Hantera fel elegant: Implementera robust felhantering för att ge en smidig användarupplevelse.
• Konsultera enhetens dokumentation: Se enhetens dokumentation för att förstå dess HID-rapportbeskrivning.
• Testa på flera plattformar: Testa din applikation på olika webbläsare och operativsystem för att säkerställa kompatibilitet.
• Tänk på säkerheten: Var medveten om säkerhetskonsekvenserna när du arbetar med användarinmatning. Sanera data och undvik att exekvera opålitlig kod.
• Erbjud reservalternativ: Om WebHID inte stöds eller om användaren nekar åtkomst, erbjuda alternativa inmatningsmetoder.

Avancerade tekniker

Feature-rapporter

Utöver inmatningsrapporter kan HID-enheter också skicka och ta emot feature-rapporter. Feature-rapporter används för att konfigurera enheten eller hämta dess status.

För att skicka en feature-rapport, använd metoden device.sendFeatureReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Exempeldata

device.sendFeatureReport(reportId, data)
  .then(() => {
    console.log('Feature-rapport skickad framgångsrikt');
  })
  .catch((error) => {
    console.error('Misslyckades med att skicka feature-rapport:', error);
  });

            

              
                Copy
              
            
          

För att ta emot en feature-rapport, använd metoden device.getFeatureReport().

            const reportId = 0x01;

device.getFeatureReport(reportId)
  .then((data) => {
    console.log('Mottog feature-rapport:', data);
  })
  .catch((error) => {
    console.error('Misslyckades med att hämta feature-rapport:', error);
  });

            

              
                Copy
              
            
          

Utdatarapporter

WebHID stöder också utdatarapporter, vilka låter dig skicka data *till* enheten. Du kan till exempel använda utdatarapporter för att styra lysdioder eller andra aktuatorer på enheten.

För att skicka en utdatarapport, använd metoden device.sendReport().

            const reportId = 0x01;
const data = new Uint8Array([0x01, 0x02, 0x03]); // Exempeldata

device.sendReport(reportId, data)
  .then(() => {
    console.log('Utdatarapport skickad framgångsrikt');
  })
  .catch((error) => {
    console.error('Misslyckades med att skicka utdatarapport:', error);
  });

            

              
                Copy
              
            
          

Säkerhetsaspekter

Åtkomst till WebHID kräver användarens tillstånd, vilket hjälper till att mildra vissa säkerhetsrisker. Det är dock fortfarande viktigt att vara medveten om potentiella sårbarheter.

• Datasanering: Sanera alltid data som tas emot från HID-enheter för att förhindra kodinjektion eller andra attacker.
• Ursprungsbegränsningar: WebHID är föremål för same-origin-policyn, vilket förhindrar åtkomst till HID-enheter från andra ursprung (cross-origin).
• Användarmedvetenhet: Utbilda användare om riskerna med att bevilja åtkomst till HID-enheter och uppmuntra dem att endast ge tillstånd till betrodda webbplatser.

Globala perspektiv och exempel

WebHID API:et har globala implikationer, vilket gör det möjligt för utvecklare att skapa webbapplikationer som stöder ett brett utbud av enheter från olika tillverkare och regioner. Tänk på dessa exempel:

• Spel: Stöd för spelkontroller från olika tillverkare i olika länder (t.ex. Sony PlayStation-kontroller, Microsoft Xbox-kontroller, Nintendo Switch Pro Controller och mindre kända märken från Asien och Europa).
• Tillgänglighet: Skapa anpassade inmatningsenheter för användare med funktionsnedsättningar, med hänsyn till olika regionala tillgänglighetsstandarder och preferenser. Till exempel specialiserade tangentbord eller switch-gränssnitt utformade för specifika behov och tillgängliga i olika layouter.
• Industriell automation: Gränssnitt mot industriella styrenheter och sensorer som används i tillverkningsanläggningar runt om i världen, med stöd för olika kommunikationsprotokoll och dataformat.
• Vetenskaplig forskning: Ansluta till vetenskapliga instrument som används i forskningslaboratorier globalt, vilket gör det möjligt för forskare att samla in och analysera data direkt i webbapplikationer. Föreställ dig att styra laboratorieutrustning vid ett universitet i Tokyo från en forskares bärbara dator i London.
• Utbildning: Stöd för pedagogiska robotar och interaktiva enheter som används i klassrum världen över, vilket ger elever praktiska lärandeupplevelser. Detta kan inkludera kodningsrobotar tillverkade i Kina som används i ett klassrum i Brasilien.

WebHID kontra andra webb-API:er

Det är värt att notera hur WebHID står sig i jämförelse med andra webb-API:er relaterade till enhetsinteraktion:

• Gamepad API: Gamepad API:et erbjuder ett högnivågränssnitt specifikt för spelkontroller. WebHID erbjuder mer flexibilitet och kontroll men kräver mer manuell hantering av enhetsdata. Gamepad API:et är väl lämpat för vanliga spelkontroller, medan WebHID kan stödja mer exotiska eller specialiserade inmatningsenheter.
• WebUSB API: WebUSB tillåter webbapplikationer att kommunicera direkt med USB-enheter. WebHID är specifikt utformat för mänskliga gränssnittsenheter, medan WebUSB kan användas för ett bredare utbud av USB-enheter. WebUSB kan användas för ett specialiserat vetenskapligt instrument anslutet via USB, medan WebHID skulle användas för ett anpassat tangentbord eller en mus.
• Web Serial API: Web Serial möjliggör kommunikation över seriella portar. Detta är användbart för att interagera med inbyggda system och andra enheter som kommunicerar via seriella anslutningar. En mikrokontroller som skickar data över en seriell anslutning skulle kunna använda Web Serial, medan en specialbyggd joystick skulle använda WebHID.

Framtiden för WebHID

WebHID API:et utvecklas ständigt, med pågående ansträngningar för att förbättra dess säkerhet, prestanda och användarvänlighet. I takt med att fler enheter antar HID-standarden kommer WebHID att bli ett allt viktigare verktyg för webbutvecklare. Förvänta dig att se mer avancerade funktioner och förbättrat webbläsarstöd i framtiden.

Slutsats

WebHID är ett kraftfullt API som öppnar upp ett brett spektrum av möjligheter för webbapplikationer. Genom att förstå enhetsfilter och hur man hanterar HID-rapporter kan du skapa engagerande och interaktiva webbupplevelser som utnyttjar den fulla potentialen hos mänskliga gränssnittsenheter. Oavsett om du bygger ett spel, ett tillgänglighetsverktyg eller ett industriellt styrsystem kan WebHID hjälpa dig att ansluta din webbapplikation till den fysiska världen. Kom ihåg att prioritera användarupplevelse, säkerhet och plattformsoberoende kompatibilitet för att skapa framgångsrika och globalt tillgängliga WebHID-applikationer.